'\" t
'
' Name:		tpbundle.1m
'
' Completed:	13th August, 2004.
'
' Updated:	
'
' Purpose:	Describes the tpbundle command.
'
' Author:	Simon Edwards, Proprius Consulting Ltd.
'
' Version:	@(#)1.1 Original (SE)
'
.TH tpbundle 1M "13 August 2004" "Linuxha.net"

.SH NAME
tpbundle - Create Tarp package bundles

.SH SYNOPSIS
.TS
l.
tpbundle \fB-c\fP \fB-p\fP \fIpkg\fP \fB-b\fP \fIbundle\fP [\fB-d\fP \fIdepot\fP] [\fB-v\fP] [\fB-T\fP \fIdir\fP]
       - Create new package bundle

tplist \fB-u|-a\fP \fB-p\fP \fIpkg\fP \fB-b\fP \fIbundlefile\fP [\fB-d\fP \fIdepot\fP] [\fB-v\fP] [\fB-T\fP \fIdir\fP]
       - Add or update bundle with further packages 

tplist \fB-r\fP \fB-p\fP \fIpkg\fP \fB-b\fP \fIbundlefile\fP [\fB-d\fP \fIdepot\fP] [\fB-v\fP] [\fB-T\fP \fIdir\fP]
	- Remove packages from bundle
.TE

.SH DESCRIPTION

The \fitpbundle(1M)\fP utility is used create or update a "Tarp bundle" - a
tar file containing a number of optionally comperssed "Tarp" packages. The Tarp
package manager makes use of bundles to provide a convenient way of distributing a
series of packages as a single file.

The contents of the bundle can be installed on a per-package basis (though intra-bundle
dependency checking is performed). 

The "Tarp" package is simply a tar archive containing tar files for each of the
packages, a list of package specifications and a file containing the specification 
of the bundle itself. The Tar file format was chosen to provide a portable format that
is understood on all targeted platforms.

A bundle can contain any set of packages - including;
.TP 4
[1]
Multiple versions of the same package
.TP
[2]
Packages that are not supported on the current platform.
.RS

This means that the same bundle can be "installed" on different machines
and just packages relevant for that environment will be installed - very convenient
for software distribution!

.SH OPERATING MODES
As shown in the \fBSYNOPSIS\fP section the utility works in two different 
manners. It will either create a new bundle, or can be used to modify the contents 
of an existing one. The differences between the two are explained below;

.SS Creating a new bundle
The list of packages specified (see below) are validated and then a
Tarp bundle is created. If such a bundle already exists then an error will
be given. 

To be able to create such a bundle a "specification" file for the bundle must
to given, (the contents and format are described below).

.SS Updating an existing bundle
The complete name of the bundle file must be given and a list of packages
to add or update. The bundle contents are extracted to a temporary directory
and then the packages to add or update are added to this directory and the
bundle re-created.

In such scenarios the previously used specification file for the bundle is
kept and once complete the original bundle will have been overwritten with the
new one.

.SH DISK SPACE UTILISATION 
During the creation or modification of a bundle a temporary directory is created
which will be used to contain all the packages that are to be part of the
bundle. 

Hence the total amount of disk space required for this process is roughly twice
the size of the packages. By default it will create this temporary directory as a
sub-directory of the working directory. If this is not suitable the \fB-T\fP
option can be used to specify an alternative location.

Note that when a bundle is created or updated the packages are compressed
with Gzip if not already compressed. This ensures that the size of the bundle
is kept as small as possible.

.SH ARGUMENTS
Currently the folllowing command line options are supported:

.TP 4
.B -c
Create a new bundle - if a bundle of the specified name and version exists in the
specified depot then the process will be aborted - i.e. creating an archive will
not overwrite an existing one.
.TP
.B -a
Append / update mode - an existing bundle is changed by adding or removing the
specified list of packages. The specified bundle must already exist. In this case
the complete name of the bundle (such as "bundle,1-1-0.tarpb" must be specified.
.TP
.B -u
Update mode - currently functionaliy the same as the "-a" option.
.TP
.B -r
Remove mode - remove the specified packages from the archive (if they are present).
.TP
.B -b
This is followed by the name of the bundle to create or change. When creating a bundle,
(via the "-a" flag), just the first component of the bundle is used - "fred" for example.
When altering a bundle (via the "-a", "-u" or "-d" flags), then the complete bundle
filename should be specified - for example "fred,1-0-0.tarpb".
.TP
.B -v
Verbose mode - shows progress messages as the script executes. In the current
version of the script this adds nothing to the standard output.
.TP
.B -p
Followed by a single argument which defines the packages to perform against the
specified action - a pattern match is available - for example "*.tarp" (note that
quotes are recommended when using shell meta characters).
.TP
.B -T
Indicates the temporary directory to use to create temporary files. Within this 
directory a temporary directory will be created whilst the program runs and deleted
afterwards. For security this defaults to the current directory - though you may wish
to use "/tmp".
.TP
.B -s
If creating a bundle then this argument can be used to indicate the name of the
specification file for the package. If not specified this will default to attempting 
to use a file called "spec" in the current directory.

.SH SPECIFICATION FILE CONTENTS
When a new package bundle is created a "specification" file must be privided. This
is a text file with the following format:

.TS
l.
ATTRIBUTE:value
.TE

Currently only three attributes are requried - later versions of the software will
doubtless add more.

.TP 6
.B NAME
The name of the package - should contain only characters and can include the underscore
symbol if necessary.
.TP
.B DESCRIPTION
A single line text description (as short as possible) describing the package.
.TP
.B VERSION
The version of the bundle - it must be given as three integers, period separated.
.RE

Thus a sample specification file might be:

.TS
l.
NAME:testbundle
DESCRIPTION:Simon test bundle description
VERSION:1.2.0
.TE

.SH EXAMPLES
The first example creates a bundle containing all packages in the current directory
that contain the work "dummy". The verbose flag is used to provide feedback as the 
command runs.

.TS
l.
tpbundle -c -b fred -p "*dummy*.tarp" -v
.TE

Since the "-s" option has not been specified the above command will use the file
called "spec" in the current directory when creating the "fred" bundle. The output
from the running the command would be similar to:

.TS
l.
INFO : Depot defaulted to: /home/sedward/tmp
INFO : Spec file defaulted to: spec
INFO : Validated bundle to create does not exist.
INFO : PWD=/home/sedward/tmp
INFO : Attempting to validate package MBNA_dummy,1-0-0,HP-UX,9000800.tarp.
INFO : Validated MBNA_dummy,1-0-0,HP-UX,9000800.tarp is tarp package.
INFO : Compressing package MBNA_dummy,1-0-0,HP-UX,9000800.tarp using gzip.
INFO : Package MBNA_dummy,1-0-0,HP-UX,9000800.tarp added to bundle.
INFO : PWD=/home/sedward/tmp
INFO : Attempting to validate package MBNA_dummy2,1-0-0,HP-UX,9000800.tarp.
INFO : Validated MBNA_dummy2,1-0-0,HP-UX,9000800.tarp is tarp package.
INFO : Compressing package MBNA_dummy2,1-0-0,HP-UX,9000800.tarp using gzip.
INFO : Package MBNA_dummy2,1-0-0,HP-UX,9000800.tarp added to bundle.
INFO : Copied Spec file spec to /home/sedward/tmp/tpbundle.15095/build/spec.
INFO : Creating software bundle...
INFO : Successfully created bundle fred,1-2-0.tarpb.
.TE

The following example will add the package "pre1,1-0-0.tarp" to the 
package that has just been created:

.TS
l.

.TE

The output generated in this case would be:

.TS
l.
INFO : Depot defaulted to: /home/sedward/tmp
INFO : Spec file defaulted to: spec
INFO : Attempting to unbundle "fred,1-2-0.tarpb"...
INFO : Successfully unbundled 2 packages.
INFO : Copied 1 packages to bundle directory.
INFO : PWD=/home/sedward/tmp/tpbundle.15401
INFO : Attempting to validate package MBNA_dummy,1-0-0,HP-UX,9000800.tarp.gz.
INFO : Validated MBNA_dummy,1-0-0,HP-UX,9000800.tarp.gz is tarp package.
INFO : Package MBNA_dummy,1-0-0,HP-UX,9000800.tarp.gz added to bundle.
INFO : PWD=/home/sedward/tmp/tpbundle.15401
INFO : Attempting to validate package MBNA_dummy2,1-0-0,HP-UX,9000800.tarp.gz.
INFO : Validated MBNA_dummy2,1-0-0,HP-UX,9000800.tarp.gz is tarp package.
INFO : Package MBNA_dummy2,1-0-0,HP-UX,9000800.tarp.gz added to bundle.
INFO : PWD=/home/sedward/tmp/tpbundle.15401
INFO : Attempting to validate package pre1,1-0-0,HP-UX,9000800.tarp.
INFO : Validated pre1,1-0-0,HP-UX,9000800.tarp is tarp package.
INFO : Compressing package pre1,1-0-0,HP-UX,9000800.tarp using gzip.
INFO : Package pre1,1-0-0,HP-UX,9000800.tarp added to bundle.
INFO : Updating software bundle...
INFO : Successfully updated bundle fred,1-2-0.tarpb.
.TE

.SH EXIT CODES
The utility makes use of the following exit codes:

.TP 4
.B 0
The required bundle has been created or updated successfully.
.TP
.B 3
Bundle specified to create already exists, (when running in "create" mode).
.TP
.B 4
Unable to find the package specified to add, update or remove from the
bundle.
.TP
.B 5
Unable to create a temporary directory within the currently defined
temporary directory, (which is the current directory if the "-T" 
option has not been used).
.TP
.B 6
The specified package does not include the expected ".tarp" extension. An optional
extension for one of the supported compression types is allowed.
.TP
.B 7
The specified package does not appear to be a valid package (that it tar can not 
extract a "spec" file to the current directory from it).
.TP
.B 8
The specified depot name might not be a valid directory, or the current
ID does not have permissions to change directory to it.
.TP
.B 12
The specified bundle specification file does not exist, or is not
a regular file, or is not readable.
.TP
.B 14
A mandatory field is missing from the bundle specification file.
.TP
.B 15
The version given in the specification file does not conform to the
required "N.N.N" format.
.TP
.B 22
Unable to use Gzip to compress a package to add in the Tarp bundle. Typically occurs
if the gzip program is not available in the current \fBPATH\fP setting.
.TP
.B 23
The specified temporary directory to use does not currently exist.
.TP
.B 24
The bundle specified to update does not exist in the specified depot.
.TP
.B 25
The bundle name given does not appear to be in the expected format, (that is
it should include the .tarpb extension, optionally followed by an compression
extension).
.TP
.B 26
The specified file does not appaer to be a Tarp bundle. To be a Tarp bundle it 
expects that \fItar(1)\fP should be able to extract a file called "spec" to the 
current directory.
.TP
.B 27
Unable to pack or unpack the specified bundle - this typically occurs if the process
runs out of disk space during the unpack process.
.TP
.B 28
Unable to copy the specified file to the temporary directory - again most likely
due to lack of disk space.
.TP
.B 29
Unable to copy the package to the specified depot - either the user does not have
permissions to write to the depot, is not able to overwrite the existing bundle, 
or the file system containing the depot is currently full.
.TP
.B 99
An internal error has occured - typically used if if a function
that is not currently implemented is chosen.

.SH SEE ALSO
.BR tpchk(1M),
.BR tpinstall(1M),
.BR tpintro(1M),
.BR tplist(1M),
.BR tppkg(1M),
.BR tpremove(1M).

.SH WARRANTY/LICENSE/ENVIRONMENT
This utility is available under the GNU GPL, and comes with 
\fIno warranty or guarantee of any kind\fP.

This program is only suitable for environments that have the following
software components installed:

.TP 4
.B Shell Utilities
The following utilities are required, \fIawk(1)\fP, \fIksh(1)\fP
as well as the standard utiltiies to check, move and remove files and 
directories.
.TP
.B Perl
Any version of Perl from 4 onwards with standard installation libraries
should be suitable. Currently Perl is only used spareingly, but still must
be available.

